 /*
  * $Header: /cvshome/build/org.osgi.service.metatype/src/org/osgi/service/metatype/AttributeDefinition.java,v 1.13 2006/06/16 16:31:23 hargrave Exp $
  *
  * Copyright (c) OSGi Alliance (2001, 2006). All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.osgi.service.metatype;

 /**
  * An interface to describe an attribute.
  *
  * <p>
  * An <code>AttributeDefinition</code> object defines a description of the data
  * type of a property/attribute.
  *
  * @version $Revision: 1.13 $
  */
 public interface AttributeDefinition {
     /**
      * The <code>STRING</code> (1) type.
      *
      * <p>
      * Attributes of this type should be stored as <code>String</code>,
      * <code>Vector</code> with <code>String</code> or <code>String[]</code> objects,
      * depending on the <code>getCardinality()</code> value.
      */
     public static final int STRING = 1;
     /**
      * The <code>LONG</code> (2) type.
      *
      * Attributes of this type should be stored as <code>Long</code>,
      * <code>Vector</code> with <code>Long</code> or <code>long[]</code> objects,
      * depending on the <code>getCardinality()</code> value.
      */
     public static final int LONG = 2;
     /**
      * The <code>INTEGER</code> (3) type.
      *
      * Attributes of this type should be stored as <code>Integer</code>,
      * <code>Vector</code> with <code>Integer</code> or <code>int[]</code> objects,
      * depending on the <code>getCardinality()</code> value.
      */
     public static final int INTEGER = 3;
     /**
      * The <code>SHORT</code> (4) type.
      *
      * Attributes of this type should be stored as <code>Short</code>,
      * <code>Vector</code> with <code>Short</code> or <code>short[]</code> objects,
      * depending on the <code>getCardinality()</code> value.
      */
     public static final int SHORT = 4;
     /**
      * The <code>CHARACTER</code> (5) type.
      *
      * Attributes of this type should be stored as <code>Character</code>,
      * <code>Vector</code> with <code>Character</code> or <code>char[]</code> objects,
      * depending on the <code>getCardinality()</code> value.
      */
     public static final int CHARACTER = 5;
     /**
      * The <code>BYTE</code> (6) type.
      *
      * Attributes of this type should be stored as <code>Byte</code>,
      * <code>Vector</code> with <code>Byte</code> or <code>byte[]</code> objects,
      * depending on the <code>getCardinality()</code> value.
      */
     public static final int BYTE = 6;
     /**
      * The <code>DOUBLE</code> (7) type.
      *
      * Attributes of this type should be stored as <code>Double</code>,
      * <code>Vector</code> with <code>Double</code> or <code>double[]</code> objects,
      * depending on the <code>getCardinality()</code> value.
      */
     public static final int DOUBLE = 7;
     /**
      * The <code>FLOAT</code> (8) type.
      *
      * Attributes of this type should be stored as <code>Float</code>,
      * <code>Vector</code> with <code>Float</code> or <code>float[]</code> objects,
      * depending on the <code>getCardinality()</code> value.
      */
     public static final int FLOAT = 8;
     /**
      * The <code>BIGINTEGER</code> (9) type.
      *
      * Attributes of this type should be stored as <code>BigInteger</code>,
      * <code>Vector</code> with <code>BigInteger</code> or <code>BigInteger[]</code>
      * objects, depending on the <code>getCardinality()</code> value.
      *
      * @deprecated As of 1.1.
      */
     public static final int BIGINTEGER = 9;
     /**
      * The <code>BIGDECIMAL</code> (10) type.
      *
      * Attributes of this type should be stored as <code>BigDecimal</code>,
      * <code>Vector</code> with <code>BigDecimal</code> or <code>BigDecimal[]</code>
      * objects depending on <code>getCardinality()</code>.
      *
      * @deprecated As of 1.1.
      */
     public static final int BIGDECIMAL = 10;
     /**
      * The <code>BOOLEAN</code> (11) type.
      *
      * Attributes of this type should be stored as <code>Boolean</code>,
      * <code>Vector</code> with <code>Boolean</code> or <code>boolean[]</code> objects
      * depending on <code>getCardinality()</code>.
      */
     public static final int BOOLEAN = 11;

     /**
      * Get the name of the attribute. This name may be localized.
      *
      * @return The localized name of the definition.
      */
     public String getName();

     /**
      * Unique identity for this attribute.
      *
      * Attributes share a global namespace in the registry. E.g. an attribute
      * <code>cn</code> or <code>commonName</code> must always be a <code>String</code>
      * and the semantics are always a name of some object. They share this
      * aspect with LDAP/X.500 attributes. In these standards the OSI Object
      * Identifier (OID) is used to uniquely identify an attribute. If such an
      * OID exists, (which can be requested at several standard organisations and
      * many companies already have a node in the tree) it can be returned here.
      * Otherwise, a unique id should be returned which can be a Java class name
      * (reverse domain name) or generated with a GUID algorithm. Note that all
      * LDAP defined attributes already have an OID. It is strongly advised to
      * define the attributes from existing LDAP schemes which will give the OID.
      * Many such schemes exist ranging from postal addresses to DHCP parameters.
      *
      * @return The id or oid
      */
     public String getID();

     /**
      * Return a description of this attribute.
      *
      * The description may be localized and must describe the semantics of this
      * type and any constraints.
      *
      * @return The localized description of the definition.
      */
     public String getDescription();

     /**
      * Return the cardinality of this attribute.
      *
      * The OSGi environment handles multi valued attributes in arrays ([]) or in
      * <code>Vector</code> objects. The return value is defined as follows:
      *
      * <pre>
      *
      * x = Integer.MIN_VALUE no limit, but use Vector
      * x &lt; 0 -x = max occurrences, store in Vector
      * x &gt; 0 x = max occurrences, store in array []
      * x = Integer.MAX_VALUE no limit, but use array []
      * x = 0 1 occurrence required
      *
      * </pre>
      *
      * @return The cardinality of this attribute.
      */
     public int getCardinality();

     /**
      * Return the type for this attribute.
      *
      * <p>
      * Defined in the following constants which map to the appropriate Java
      * type. <code>STRING</code>,<code>LONG</code>,<code>INTEGER</code>,
      * <code>CHAR</code>,<code>BYTE</code>,<code>DOUBLE</code>,<code>FLOAT</code>,
      * <code>BOOLEAN</code>.
      *
      * @return The type for this attribute.
      */
     public int getType();

     /**
      * Return a list of option values that this attribute can take.
      *
      * <p>
      * If the function returns <code>null</code>, there are no option values
      * available.
      *
      * <p>
      * Each value must be acceptable to validate() (return "") and must be a
      * <code>String</code> object that can be converted to the data type defined
      * by getType() for this attribute.
      *
      * <p>
      * This list must be in the same sequence as <code>getOptionLabels()</code>.
      * I.e. for each index i in <code>getOptionValues</code>, i in
      * <code>getOptionLabels()</code> should be the label.
      *
      * <p>
      * For example, if an attribute can have the value male, female, unknown,
      * this list can return
      * <code>new String[] { "male", "female", "unknown" }</code>.
      *
      * @return A list values
      */
     public String [] getOptionValues();

     /**
      * Return a list of labels of option values.
      *
      * <p>
      * The purpose of this method is to allow menus with localized labels. It is
      * associated with <code>getOptionValues</code>. The labels returned here are
      * ordered in the same way as the values in that method.
      *
      * <p>
      * If the function returns <code>null</code>, there are no option labels
      * available.
      * <p>
      * This list must be in the same sequence as the <code>getOptionValues()</code>
      * method. I.e. for each index i in <code>getOptionLabels</code>, i in
      * <code>getOptionValues()</code> should be the associated value.
      *
      * <p>
      * For example, if an attribute can have the value male, female, unknown,
      * this list can return (for dutch)
      * <code>new String[] { "Man", "Vrouw", "Onbekend" }</code>.
      *
      * @return A list values
      */
     public String [] getOptionLabels();

     /**
      * Validate an attribute in <code>String</code> form.
      *
      * An attribute might be further constrained in value. This method will
      * attempt to validate the attribute according to these constraints. It can
      * return three different values:
      *
      * <pre>
      * null No validation present
      * "" No problems detected
      * "..." A localized description of why the value is wrong
      * </pre>
      *
      * @param value The value before turning it into the basic data type
      * @return <code>null</code>, "", or another string
      */
     public String validate(String value);

     /**
      * Return a default for this attribute.
      *
      * The object must be of the appropriate type as defined by the cardinality
      * and <code>getType()</code>. The return type is a list of <code>String</code>
      * objects that can be converted to the appropriate type. The cardinality of
      * the return array must follow the absolute cardinality of this type. E.g.
      * if the cardinality = 0, the array must contain 1 element. If the
      * cardinality is 1, it must contain 0 or 1 elements. If it is -5, it must
      * contain from 0 to max 5 elements. Note that the special case of a 0
      * cardinality, meaning a single value, does not allow arrays or vectors of
      * 0 elements.
      *
      * @return Return a default value or <code>null</code> if no default exists.
      */
     public String [] getDefaultValue();
 }

